\section{TiXmlHandle Class Reference}
\label{classTiXmlHandle}\index{TiXmlHandle@{TiXmlHandle}}
{\tt \#include $<$tinyxml.h$>$}



\subsection{Detailed Description}
A \doxyref{TiXmlHandle}{p.}{classTiXmlHandle} is a class that wraps a node pointer with null checks; this is an incredibly useful thing. Note that \doxyref{TiXmlHandle}{p.}{classTiXmlHandle} is not part of the TinyXml DOM structure. It is a separate utility class.

Take an example: 

\footnotesize\begin{verbatim}
	<Document>
		<Element attributeA = "valueA">
			<Child attributeB = "value1" />
			<Child attributeB = "value2" />
		</Element>
	<Document>
	\end{verbatim}
\normalsize


Assuming you want the value of \char`\"{}attributeB\char`\"{} in the 2nd \char`\"{}Child\char`\"{} element, it's very easy to write a $\ast$lot$\ast$ of code that looks like:



\footnotesize\begin{verbatim}
	TiXmlElement* root = document.FirstChildElement( "Document" );
	if ( root )
	{
		TiXmlElement* element = root->FirstChildElement( "Element" );
		if ( element )
		{
			TiXmlElement* child = element->FirstChildElement( "Child" );
			if ( child )
			{
				TiXmlElement* child2 = child->NextSiblingElement( "Child" );
				if ( child2 )
				{
					// Finally do something useful.
	\end{verbatim}
\normalsize


And that doesn't even cover \char`\"{}else\char`\"{} cases. \doxyref{TiXmlHandle}{p.}{classTiXmlHandle} addresses the verbosity of such code. A \doxyref{TiXmlHandle}{p.}{classTiXmlHandle} checks for null pointers so it is perfectly safe and correct to use:



\footnotesize\begin{verbatim}
	TiXmlHandle docHandle( &document );
	TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
	if ( child2 )
	{
		// do something useful
	\end{verbatim}
\normalsize


Which is MUCH more concise and useful.

It is also safe to copy handles - internally they are nothing more than node pointers. 

\footnotesize\begin{verbatim}
	TiXmlHandle handleCopy = handle;
	\end{verbatim}
\normalsize


What they should not be used for is iteration:



\footnotesize\begin{verbatim}
	int i=0; 
	while ( true )
	{
		TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
		if ( !child )
			break;
		// do something
		++i;
	}
	\end{verbatim}
\normalsize


It seems reasonable, but it is in fact two embedded while loops. The Child method is a linear walk to find the element, so this code would iterate much more than it needs to. Instead, prefer:



\footnotesize\begin{verbatim}
	TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();

	for( child; child; child=child->NextSiblingElement() )
	{
		// do something
	}
	\end{verbatim}
\normalsize
 \subsection*{Public Member Functions}
\begin{CompactItemize}
\item 
{\bf TiXmlHandle} ({\bf TiXmlNode} $\ast$\_\-node)
\begin{CompactList}\small\item\em Create a handle from any node (at any depth of the tree.) This can be a null pointer. \item\end{CompactList}\item 
{\bf TiXmlHandle} (const {\bf TiXmlHandle} \&ref)
\begin{CompactList}\small\item\em Copy constructor. \item\end{CompactList}\item 
{\bf TiXmlHandle} {\bf operator=} (const {\bf TiXmlHandle} \&ref)
\item 
{\bf TiXmlHandle} {\bf FirstChild} () const 
\begin{CompactList}\small\item\em Return a handle to the first child node. \item\end{CompactList}\item 
{\bf TiXmlHandle} {\bf FirstChild} (const char $\ast$value) const 
\begin{CompactList}\small\item\em Return a handle to the first child node with the given name. \item\end{CompactList}\item 
{\bf TiXmlHandle} {\bf FirstChildElement} () const 
\begin{CompactList}\small\item\em Return a handle to the first child element. \item\end{CompactList}\item 
{\bf TiXmlHandle} {\bf FirstChildElement} (const char $\ast$value) const 
\begin{CompactList}\small\item\em Return a handle to the first child element with the given name. \item\end{CompactList}\item 
{\bf TiXmlHandle} {\bf Child} (const char $\ast$value, int index) const 
\item 
{\bf TiXmlHandle} {\bf Child} (int index) const 
\item 
{\bf TiXmlHandle} {\bf ChildElement} (const char $\ast$value, int index) const 
\item 
{\bf TiXmlHandle} {\bf ChildElement} (int index) const 
\item 
{\bf TiXmlNode} $\ast$ {\bf ToNode} () const 
\item 
{\bf TiXmlElement} $\ast$ {\bf ToElement} () const 
\item 
{\bf TiXmlText} $\ast$ {\bf ToText} () const 
\item 
{\bf TiXmlUnknown} $\ast$ {\bf ToUnknown} () const 
\item 
{\bf TiXmlNode} $\ast$ {\bf Node} () const 
\item 
{\bf TiXmlElement} $\ast$ {\bf Element} () const 
\item 
{\bf TiXmlText} $\ast$ {\bf Text} () const 
\item 
{\bf TiXmlUnknown} $\ast$ {\bf Unknown} () const 
\end{CompactItemize}


\subsection{Constructor \& Destructor Documentation}
\index{TiXmlHandle@{TiXmlHandle}!TiXmlHandle@{TiXmlHandle}}
\index{TiXmlHandle@{TiXmlHandle}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}TiXmlHandle::TiXmlHandle ({\bf TiXmlNode} $\ast$ {\em \_\-node})\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_ba18fd7bdefb942ecdea4bf4b8e29ec8}


Create a handle from any node (at any depth of the tree.) This can be a null pointer. 

\index{TiXmlHandle@{TiXmlHandle}!TiXmlHandle@{TiXmlHandle}}
\index{TiXmlHandle@{TiXmlHandle}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}TiXmlHandle::TiXmlHandle (const {\bf TiXmlHandle} \& {\em ref})\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_236d7855e1e56ccc7b980630c48c7fd7}


Copy constructor. 



\subsection{Member Function Documentation}
\index{TiXmlHandle@{TiXmlHandle}!operator=@{operator=}}
\index{operator=@{operator=}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::operator= (const {\bf TiXmlHandle} \& {\em ref})\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_d8e5dcf6a87882674203157f29f8e4db}


\index{TiXmlHandle@{TiXmlHandle}!FirstChild@{FirstChild}}
\index{FirstChild@{FirstChild}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::FirstChild () const}\label{classTiXmlHandle_cdb1faaf88a700b40ca2c8d9aee21139}


Return a handle to the first child node. 

\index{TiXmlHandle@{TiXmlHandle}!FirstChild@{FirstChild}}
\index{FirstChild@{FirstChild}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::FirstChild (const char $\ast$ {\em value}) const}\label{classTiXmlHandle_8c61f64ae9365d89c264f289085541f8}


Return a handle to the first child node with the given name. 

\index{TiXmlHandle@{TiXmlHandle}!FirstChildElement@{FirstChildElement}}
\index{FirstChildElement@{FirstChildElement}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::FirstChildElement () const}\label{classTiXmlHandle_24d1112e995e937e4dddb202d4113d4a}


Return a handle to the first child element. 

\index{TiXmlHandle@{TiXmlHandle}!FirstChildElement@{FirstChildElement}}
\index{FirstChildElement@{FirstChildElement}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::FirstChildElement (const char $\ast$ {\em value}) const}\label{classTiXmlHandle_f0aea751320f5e430fac6f8fff3b8dd4}


Return a handle to the first child element with the given name. 

\index{TiXmlHandle@{TiXmlHandle}!Child@{Child}}
\index{Child@{Child}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::Child (const char $\ast$ {\em value}, int {\em index}) const}\label{classTiXmlHandle_072492b4be1acdb0db2d03cd8f71ccc4}


Return a handle to the \char`\"{}index\char`\"{} child with the given name. The first child is 0, the second 1, etc. \index{TiXmlHandle@{TiXmlHandle}!Child@{Child}}
\index{Child@{Child}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::Child (int {\em index}) const}\label{classTiXmlHandle_f9cf6a7d08a5da94a8924425ad0cd5ac}


Return a handle to the \char`\"{}index\char`\"{} child. The first child is 0, the second 1, etc. \index{TiXmlHandle@{TiXmlHandle}!ChildElement@{ChildElement}}
\index{ChildElement@{ChildElement}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::ChildElement (const char $\ast$ {\em value}, int {\em index}) const}\label{classTiXmlHandle_979a3f850984a176ee884e394c7eed2d}


Return a handle to the \char`\"{}index\char`\"{} child element with the given name. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. \index{TiXmlHandle@{TiXmlHandle}!ChildElement@{ChildElement}}
\index{ChildElement@{ChildElement}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlHandle} TiXmlHandle::ChildElement (int {\em index}) const}\label{classTiXmlHandle_8786475b9d1f1518492e3a46704c7ef0}


Return a handle to the \char`\"{}index\char`\"{} child element. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. \index{TiXmlHandle@{TiXmlHandle}!ToNode@{ToNode}}
\index{ToNode@{ToNode}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlNode}$\ast$ TiXmlHandle::ToNode () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_f678e5088e83be67baf76f699756f2c3}


Return the handle as a \doxyref{TiXmlNode}{p.}{classTiXmlNode}. This may return null. \index{TiXmlHandle@{TiXmlHandle}!ToElement@{ToElement}}
\index{ToElement@{ToElement}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlElement}$\ast$ TiXmlHandle::ToElement () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_bc6e7ed383a5fe1e52b0c0004b457b9e}


Return the handle as a \doxyref{TiXmlElement}{p.}{classTiXmlElement}. This may return null. \index{TiXmlHandle@{TiXmlHandle}!ToText@{ToText}}
\index{ToText@{ToText}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlText}$\ast$ TiXmlHandle::ToText () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_4ac53a652296203a5b5e13854d923586}


Return the handle as a \doxyref{TiXmlText}{p.}{classTiXmlText}. This may return null. \index{TiXmlHandle@{TiXmlHandle}!ToUnknown@{ToUnknown}}
\index{ToUnknown@{ToUnknown}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlUnknown}$\ast$ TiXmlHandle::ToUnknown () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_1381c17507a130767b1e23afc93b3674}


Return the handle as a \doxyref{TiXmlUnknown}{p.}{classTiXmlUnknown}. This may return null. \index{TiXmlHandle@{TiXmlHandle}!Node@{Node}}
\index{Node@{Node}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlNode}$\ast$ TiXmlHandle::Node () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_b44b723a8dc9af72838a303c079d0376}


\begin{Desc}
\item[{\bf Deprecated}]use ToNode. Return the handle as a \doxyref{TiXmlNode}{p.}{classTiXmlNode}. This may return null. \end{Desc}
\index{TiXmlHandle@{TiXmlHandle}!Element@{Element}}
\index{Element@{Element}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlElement}$\ast$ TiXmlHandle::Element () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_cb5fe8388a526289ea65e817a51e05e7}


\begin{Desc}
\item[{\bf Deprecated}]use ToElement. Return the handle as a \doxyref{TiXmlElement}{p.}{classTiXmlElement}. This may return null. \end{Desc}
\index{TiXmlHandle@{TiXmlHandle}!Text@{Text}}
\index{Text@{Text}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlText}$\ast$ TiXmlHandle::Text () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_9fc739c8a18d160006f82572fc143d13}


\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{ToText()}{p.}{classTiXmlHandle_4ac53a652296203a5b5e13854d923586} Return the handle as a \doxyref{TiXmlText}{p.}{classTiXmlText}. This may return null. \end{Desc}
\index{TiXmlHandle@{TiXmlHandle}!Unknown@{Unknown}}
\index{Unknown@{Unknown}!TiXmlHandle@{TiXmlHandle}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf TiXmlUnknown}$\ast$ TiXmlHandle::Unknown () const\hspace{0.3cm}{\tt  [inline]}}\label{classTiXmlHandle_49675b74357ba2aae124657a9a1ef465}


\begin{Desc}
\item[{\bf Deprecated}]use \doxyref{ToUnknown()}{p.}{classTiXmlHandle_1381c17507a130767b1e23afc93b3674} Return the handle as a \doxyref{TiXmlUnknown}{p.}{classTiXmlUnknown}. This may return null. \end{Desc}


The documentation for this class was generated from the following files:\begin{CompactItemize}
\item 
/home/msneddon/eclipse/ganymede\_\-cpp/workspace/NFsim\_\-svn/src/NFinput/TinyXML/{\bf tinyxml.h}\item 
/home/msneddon/eclipse/ganymede\_\-cpp/workspace/NFsim\_\-svn/src/NFinput/TinyXML/{\bf tinyxml.cpp}\end{CompactItemize}
